INTRODUCTION

AspNTUser.dll is an active server component for managing Windows NT domain and local users and groups in the Microsoft IIS/Active Server Pages environment. The component is designed as a hierarchy of OLE Automation (ActiveX Server) objects and collections to provide an ASP or VB developer with a simple and intuitive programming interface.

Please read the Disclaimer before installing and using the component.

INSTALLATION

Copy AspNTUser.dll to any directory on your Windows NT server, e.g. c:\mydir. Register the component by executing the command

REGSVR32 c:\mydir\AspNTUser.dll

OBJECT REFERENCE

UserManager Object

This is the top-level object that can be created by

<OBJECT RUNAT=SERVER PROGID="Persits.UserManager.1" ID=UM>

</OBJECT>

or

Set UM = Server.CreateObject("Persits.UserManager.1")

This object provides most of the functionality as well as serves as the "object factory" for Group and User objects and collections.
 

UserManager Properties

Name	Type (access)	Comments
Domain	String (read/write)	Specifies the domain on which all the commands will be executed. Use this property only if you need to manage domains other that one the component in installed on. Otherwise leave this property empty.
Server	String (read/write)	Use this property to specify the server on which all the local commands will be executed. The server name must begin with '\\'. Empty if the local machine is used.
DomainController	String (read-only)	Returns the name of the domain controller.
Groups	Object (read-only)	Returns the Groups collection of the Domain groups.
LocalGroups	Object (read-only)	Returns the Groups collection of the local groups (i.e. groups local to the machine specified by the Server property).
Users	Object (read-only)	Returns the Users collection of the Domain users.
LocalUsers	Object (read-only)	Returns the Users collection of the local users (i.e. users local to the machine specified by the Server property).

 
UserManager Methods

NOTE: The following methods throw exceptions in case of an error. They are also subject to Windows NT security restrictions. If you do not have sufficient rights to execute a method, the Access Denied exception will be thrown.

 

Name	Return Type	Arguments	Comments
LogonUser	Long	Domain: String UserID: String Password: String	Impersonates the specified Windows NT user account. All of the following operations will be performed in the security context of this account. If Domain is empty, the local account database will be used to validate the password. The user must have the "Act as Part of the Operating System" privilege for this method to work.
RevertToSelf	Long	-	Terminates the impersonation begun by LogonUser.
ChangePassword	Long	Domain: String UserName: String OldPassword: String NewPassword: String	Changes a user’s password for a specified network server or domain. If the domain is empty, the local machine is assumed.
AddLocalGroup	Object	Name: String Comment: String	Adds a new local group. Returns the Group object representing the newly created group, or Nothing if the creation failed.
AddGroup	Object	Name: String Comment: String	Adds a new domain group. Returns the Group object representing the newly created group, or Nothing if the creation failed.
AddLocalUser	Object	Name: String Password: String Comment: String	Adds a new local user. Returns the User object representing the newly created user, or Nothing if the creation failed.  Use the User object properties and methods to set additional user account properties.
AddUser	Object	Name: String Password: String Comment: String	Adds a new domain user. Returns the User object representing the newly created user, or Nothing if the creation failed.  Use the User object properties and methods to set additional user account properties.
DeleteLocalGroup	Long	Name: String	Deletes a local group.
DeleteGroup	Long	Name: String	Deletes a domain group.
DeleteLocalUser	Long	Name: String	Deletes a local user account
DeleteUser	Long	Name: String	Deletes a domain user account
GetGroup	Object	Name: String; Optional Global = True	Returns a Group object. If Global is True (default) a domain group object is returned, otherwise a local user object is returned.     Unlike Group and LocalGroups collections, this method allows you to retrieve a single group account without loading all group accounts into memory. Use this method if your NT account database contains a large number of groups.
GetUser	Object	Name: String; Optional Global = True	Returns a User object. If Global is True (default) a domain user object is returned, otherwise a local user object is returned.  Unlike Users and LocalUsers collections, this method allows you to retrieve a single user account's information without loading all user accounts into memory. Use this method if your NT account database contains a large number of users.

Users Object
Users Object is an OLE Automation collection of User objects. It implements properties and methods common to every OLE Automation collection object, such as Count and Item. The Item property is a default property. A Users collection can be used as follows:

 
Group Object
The Group object represents a local or domain Windows NT group.

Group Properties

Property	Type (access)	Comments
Name	String (read only)	Default property. Specifies a group's name.
Comment	String (read/write)	Specifies a group's comment.
Users	Object (read only)	Specifies the Users collection of domain members of this group.
LocalUsers	Object (read only)	Specifies the Users collection of local members of this group.
IsLocal	Boolean (read only)	TRUE if the group is a local group. FALSE if the group is a domain group.

Group Methods

NOTE: The following methods throw exceptions in case of an error. They are also subject to Windows NT security restrictions. If you do not have sufficient rights to execute a method, the Access Denied exception will be thrown.

Method	Type	Arguments	Comments
AddMember	Long	Name: String	Adds a member to this group. A member can be a user or, for local groups, a domain group.
DeleteMember	Long	Name: String	Deletes a member from a group.
SetInfo	Long		Saves comment information to the Windows NT account database.

User Object
The User object represents a Windows NT user account (local or domain).

 
User Properties

Property	Type (access)	Comments
Name	String (read-only)	Default property. Specifies the user's name.
Comment	String (read/write)	Specifies the user's comment.
FullName	String (read/write)	Specifies the user's full name.
PasswordAge	Long (read only)	Specifies the number of seconds elapsed since the user password was last changed.
HomeDir	String (read/write)	Specifies the user's home directory.
ScriptPath	String (read/write)	Specifies the user's logon script.
LastLogon	Date (read only)	Specifies when the last logon occurred.
LastLogoff	Date (read only)	Specifies when the last logoff occurred.
CannotChangePassword	Boolean (read/write)	Specifies whether a user can change the password.
AccountExpires	Date (read only)	Specifies the date the account expires. Returns 9/9/9999 if the account never expires.
PasswordNeverExpires	Boolean (read/write)	Specifies whether the password should expire.
AccountDisabled	Boolean (read/write)	Specifies whether the account is disabled.
AccountLockedOut	Boolean (read/write)	Specifies whether the account is locked out.
Password	String (write only)	Specifies the user's password. Use this property to set a user's new password. Does not return a valid value since Windows NT passwords are always scrambled.
Groups	Object (read only)	Returns the Groups collection of domain groups this user belongs to.
LocalGroups	Object (read only)	Returns the Groups collection of local groups this user belongs to.
Dialin	Boolean (read only)	Returns True if dial-in permission is enabled for this user.  Use User.SetDialinPermission method to change this property.
CallBackType	Integer (read only)	Returns the dial-in call back type. Possible values are: 1 - No call back. 2 - Set by caller. 3 - Preset by administrator.  Use User.SetDialinPermission method to change this property.
PhoneNumber	String (read only)	Returns the administrator-set phone number. The value returned is only valid if User.CallBackType = 3 (Preset by administrator). Use User.SetDialinPermission method to change this property.

User Methods

NOTE: The following methods throw exceptions in case of an error. They are also subject to Windows NT security restrictions. If you do not have sufficient rights to execute a method, the Access Denied exception will be thrown.

Methods	Type	Arguments	Comments
AddToGroup	Long	Name: String	Adds this user to the specified group.
DeleteFromGroup	Long	Name: String	Deletes this user from the specified group.
SetInfo	Long		Saves information specified via the User read/write and write-only properties to the Windows NT account database.
Rename	Long	Name: String	Renames this user.
SetDialinPermission	Void	CallBackType: Integer Optional Enable: Boolean Optional PhoneNumber: String	Sets dial-in permission properties for this user.  CallBackType specifies the dial-in call back type (see User.CallBackType property for possible values). Enable = True (default) enables dial-in permission. Enable = False disables it.  PhoneNumber specifies the administrator-set callback phone number. Ignored unless CallBackType = 3. Empty by default.


 

Number	Description
1	Access Denied
2	Index out of range.
3	User not found.
4	Group not found.
5	Unknown type.
6	AddUser failed.
7	GetInfo failed.
8	User exists.
9	Miscellaneous error.
10	Invalid Computer.
11	Password too short.
12	Group exists.
13	Operation allowed only on primary domain.
14	Operation not allowed on specified special groups.
15	Bad user name.
16	No such member.
17	LogonUser failed.
18	Invalid password.
19	Component expired.
20	Privilege not held.
21	Unknown user or bad password.
23	No such domain.

Click here for the AspNTUser FAQ.

CODE SAMPLES

The AspNTUser component comes with AspUserManager, an ASP application implementing most of the functions of Windows NT User Manager and User Manger for Domains. The starting ASP file is Login.asp. The AspUserManager files are a great source of code samples for the AspNTUser component.
 

Please contact Persits Software, Inc. at info@persits.com or visit our Web site at http://www.persits.com.

HISTORY OF CHANGES/FIXES

Version 1.06:

• UM.GetGroup method added.
Version 1..05:
• "No such domain" error handler added.
• Bug fixed in all collections that prevented re-entrance using For-Each.
• Buffer size increased in NetUserGetLocalGroups and NetUserGetGroups.
Version 1.04
• Multiple domain handling added via the Domain property of UserManager.
• Dialin permission handling added to the User object.
• Error handling improved (more info generated on Privilege not held, error handler added to the RevertToSelf calls).]
Version 1.03
• ThreadingModel =Apartment added to the self-registration code to make IIS run AspNTUser in the right security context and in a multi-threaded environement.
• "Bad user name or invalid password" error handler added.
• Miscellaneous error handler improved.
• GetUser method added.
Version 1.02
• Bug fixed: "Set users = UM.Groups("Domain Admins").Users" would give error 2221 if UM.Server is not set to UM.DomainController
• Bug fixed: if user.AddToGroup is called before user.SetInfo you get error 87.
• Group and User Item property now accepts Dispatch pointers, as in UM.Users( Request.ServerVariables("LOGON_USER")). Typecasting to String is no longer required.
• Missing CloseHandle bug in LogonUser (causing an Invalid Password message) fixed.
• ChangePassword.asp enhanced to demonstrate both local and domain user password change.
Version 1.01:
• User Property AccountExpires added.
• User Properties LastLogon and LastLogoff fixed.
• Users.Item() now accepts fully qualified user names in the form "DomainName\UserName".